/**
 * @copyright Copyright (c) 2025 CSG Digital Grid Technology (Guangdong) Co., Ltd.
 * @author Xie Jinhui
 */

/**
 * @brief  Log management module, mainly responsible for log management initialization and destruction
 * This header file defines the interface for a comprehensive logging system that provides
 * structured log message handling with multiple severity levels. The module supports
 * both initialization and cleanup operations along with flexible log output formatting.
 */

/* 
 * Header guard macro definition to prevent multiple inclusions
 * This preprocessor directive ensures the contents of this header file
 * are included only once during compilation, avoiding redefinition errors
 * Standard C practice for header file protection in multi-file projects
 */
#ifndef LOG_MANAGE_H

/* 
 * Define the header guard macro that marks the beginning of protected code
 * When the preprocessor encounters subsequent includes of this file,
 * it will skip the contents because LOG_MANAGE_H is already defined
 */
#define LOG_MANAGE_H

/* 
 * Enumeration definition for log message severity levels
 * This enum provides a hierarchical classification system for log messages
 * allowing developers to categorize messages by importance and severity
 * Each level represents a different type of diagnostic information
 */
typedef enum
{
    /* 
     * Verbose logging level - most detailed information
     * Used for tracing program execution flow and detailed debugging
     * Typically disabled in production builds due to high volume
     * Value: 0 - Lowest severity level in the hierarchy
     */
    MSG_VERBOSE = 0,

    /* 
     * Debug logging level - development and troubleshooting information
     * Contains information useful for debugging during development
     * May include variable values, function entry/exit points
     * Value: 1 - Second level in the severity hierarchy
     */
    MSG_DEBUG,

    /* 
     * Informational logging level - general operational messages
     * Used for reporting normal application behavior and milestones
     * Provides high-level overview of application execution flow
     * Value: 2 - Middle level in the severity hierarchy
     */
    MSG_INFO,

    /* 
     * Warning logging level - potential issues and unusual conditions
     * Indicates situations that might require attention but don't stop execution
     * Used for recoverable errors and unexpected but handled conditions
     * Value: 3 - Higher level in the severity hierarchy
     */
    MSG_WARNING,

    /* 
     * Error logging level - serious problems and failure conditions
     * Used for reporting errors that affect functionality but may not crash the application
     * Indicates conditions that prevent normal operation or data loss
     * Value: 4 - Highest severity level in the hierarchy
     */
    MSG_ERROR
}log_level_enum;

/* 
 * Function declaration for initializing the logging subsystem
 * @param: None
 * @return: void
 * This function performs one-time setup operations for the logging system
 * including opening log files, initializing internal buffers, setting up
 * output destinations, and configuring default logging parameters
 */
void init_log();

/* 
 * Function declaration for writing log messages with formatted output
 * @param level: Integer specifying the severity level of the log message
 * @param fmt: Format string specifying the message structure (printf-style)
 * @param ...: Variable arguments list for format string placeholders
 * @return: void
 * This function provides the main logging interface that accepts formatted
 * messages with variable arguments. It handles timestamp generation,
 * severity level formatting, and output routing based on configuration
 */
void write_log(int level, const char *fmt, ...);

/* 
 * Function declaration for closing and cleaning up the logging subsystem
 * @param: None
 * @return: void
 * This function performs cleanup operations when the logging system is
 * no longer needed, including flushing buffers, closing log files,
 * releasing allocated memory, and terminating logging threads
 */
void close_log();

/* 
 * End of header guard conditional compilation section
 * This comment marks the termination point of the protected header content
 * that is conditionally included based on the LOG_MANAGE_H macro definition
 */
#endif // LOG_MANAGE_H